/**
 * @file smart_timer.h
 * @brief 智能定时器组件头文件
 * 
 * 该组件提供了一个灵活的定时器管理系统，支持多种定时模式和动作类型。
 * 定时器配置可以持久化存储，系统重启后自动恢复。
 */

#ifndef __SMART_TIMER_H__
#define __SMART_TIMER_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stdbool.h>

/**
 * @brief 定时器动作类型枚举
 */
typedef enum __attribute__((packed)) {
    TIMER_ACTION_ON,     ///< 开启动作
    TIMER_ACTION_OFF,    ///< 关闭动作
    TIMER_ACTION_TOGGLE  ///< 切换状态动作
} timer_action_t;

/**
 * @brief 定时器类型枚举
 */
typedef enum __attribute__((packed)) {
    TIMER_TYPE_ONCE,     ///< 单次执行：触发一次后自动禁用
    TIMER_TYPE_DAILY,    ///< 每日重复：每天在指定时间触发
    TIMER_TYPE_WEEKLY,   ///< 每周重复：在每周指定的日期和时间触发
    TIMER_TYPE_PERIOD    ///< 时间段模式：在起始时间和结束时间分别触发不同动作
} timer_type_t;

/**
 * @brief 定时器配置结构体
 */
typedef struct {
    uint8_t id;                 ///< 定时器唯一标识符 (1-255, 0表示无效)
    timer_type_t type;          ///< 定时器类型
    timer_action_t action;      ///< 触发时执行的动作
    timer_action_t end_action;  ///< 时间段模式下结束时执行的动作
    
    struct {
        uint8_t hour;           ///< 触发时间：小时 (0-23)
        uint8_t minute;         ///< 触发时间：分钟 (0-59)
        uint8_t second;         ///< 触发时间：秒 (0-59)
        uint8_t day_mask;       ///< 周重复掩码，每一位代表一天 (bit0=周日...bit6=周六)
    } time;                     ///< 定时器触发时间配置
    
    struct {
        uint8_t hour;           ///< 结束时间：小时
        uint8_t minute;         ///< 结束时间：分钟
        uint8_t second;         ///< 结束时间：秒
    } end_time;                 ///< 时间段模式的结束时间配置
    
    bool enabled;               ///< 定时器启用状态
    time_t last_trigger_time;   ///< 上次触发时间，用于防止重复触发
    bool in_period;             ///< 仅用于时间段模式：标记当前是否在时间段内
} timer_config_t;

/**
 * @brief 定时器错误码枚举
 */
typedef enum {
    TIMER_OK = 0,                    ///< 操作成功
    TIMER_ERR_INVALID_ARG = -1,      ///< 参数无效
    TIMER_ERR_NO_MEM = -2,           ///< 内存分配失败
    TIMER_ERR_NOT_FOUND = -3,        ///< 指定的定时器不存在
    TIMER_ERR_INVALID_STATE = -4,    ///< 组件状态错误
    TIMER_ERR_TIMEOUT = -5,          ///< 操作超时
    TIMER_ERR_STORAGE = -6,          ///< 存储操作失败
    TIMER_ERR_FULL = -7,             ///< 定时器数量已达上限
    TIMER_ERR_TASK = -8,             ///< 任务创建失败
    TIMER_ERR_INVALID_SIZE = -9,     ///< 缓冲区大小不足
} timer_err_t;

/**
 * @brief 初始化智能定时器组件
 * @param max_timers 支持的最大定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_init(uint8_t max_timers);

/**
 * @brief 反初始化智能定时器组件
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_deinit(void);

/**
 * @brief 添加新的定时器
 * @param config 定时器配置
 * @param timer_id 返回的定时器ID
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_add(const timer_config_t *config, uint8_t *timer_id);

/**
 * @brief 删除指定的定时器
 * @param timer_id 要删除的定时器ID
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_delete(uint8_t timer_id);

/**
 * @brief 删除所有定时器
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_delete_all(void);

/**
 * @brief 更新定时器配置
 * @param config 新的定时器配置
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_update(const timer_config_t *config);

/**
 * @brief 设置定时器启用状态
 * @param timer_id 定时器ID
 * @param enable 是否启用
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_set_enabled(uint8_t timer_id, bool enable);

/**
 * @brief 获取所有定时器列表
 * @param timers 定时器配置数组
 * @param count 输入时表示数组大小，输出时表示实际定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_get_list(timer_config_t *timers, uint8_t *count);

/**
 * @brief 获取指定定时器的配置
 * @param timer_id 定时器ID
 * @param config 返回的定时器配置
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_get(uint8_t timer_id, timer_config_t *config);

/**
 * @brief 强制保存定时器配置到存储
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_save(void);

/**
 * @brief 获取调度器状态
 * @param running 输出参数，表示调度器是否正在运行
 * @param timer_count 输出参数，表示当前定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_get_scheduler_status(bool *running, uint8_t *timer_count);

/**
 * @brief 暂停/恢复调度器
 * @param pause 是否暂停
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_pause_resume(bool pause);

/**
 * @brief 注册定时器触发回调函数
 * @param callback 回调函数指针
 * @param user_data 用户数据指针，会在回调时传入
 * @return timer_err_t 操作结果
 */
timer_err_t smart_timer_register_callback(void (*callback)(uint8_t timer_id, timer_action_t action, void *user_data), void *user_data); 

#ifdef __cplusplus
}
#endif

#endif // __SMART_TIMER_H__
